home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.arc / gem10.asc < prev    next >
Text File  |  1987-10-10  |  12KB  |  249 lines
  1.                         *PROFESSIONAL GEM*
  2.                            by Tim Oren
  3.              Column #10 -  VDI Graphics: Text Output
  4.  
  5.      This  issue of ST PRO GEM concludes the two column series  on
  6. VDI  with a look at simple VDI  text output,  and ways to optimize
  7. its  speed.   There is also a Feedback section.   You may find the
  8. associated  download  file under the name GMCL10.C in DL3  of  the
  9. ATARI16 SIG (PCS-58).
  10.  
  11.      To  keep  the size of this first discussion  of  text  within
  12. reason, I am going to restrict it to use of the mono-spaced system
  13. font   in  its  default  size  and  orientation.    Discussion  of
  14. alternate and proportionally spaced fonts,  baseline rotation, and
  15. character scaling will become a later article in this series.
  16.  
  17.      DEFINITIONS.   This  article  makes use of  some  terminology
  18. which may be unfamiliar if you have not used digital typefaces.  A
  19. mono-spaced  font  is  one in which  each  character  occupies  an
  20. identically  wide  space on the screen.   A proportional font  has
  21. characters  which occupy different widths.   For instance,  an 'l'
  22. would probably be narrower than a 'w'.
  23.  
  24.     Text may be "justified" right,  left,  or center.  This means
  25. that  the right character,  left character,  or center position of
  26. the  text  string is constrained to a given location.   In  common
  27. usage,  a  page  of text is "ragged right" if its lines  are  left
  28. justified only.   The text page is "fully justified",  "justified"
  29. or  (ambiguously)  "right justified" if BOTH the  left  and  right
  30. characters are contrained to fixed columns.  Full justification is
  31. produced  by  inserting extra blank characters in the  case  of  a
  32. mono-spaced font,  or by adding extra pixel columns in the case of
  33. proportional output.
  34.  
  35.      A  text character (in a monospaced font) is written inside  a
  36. standard sized cell or box.  Vertically, the cell extends from the
  37. "top  line" down to the "bottom line".   If there are one or  more
  38. blank  lines at the top or bottom,  they are called "leading"  and
  39. are  used  to separate lines of text.   The characters  themselves
  40. always  fall between the "ascent line",  which is the highest line
  41. reached by characters such as 'd' and 'l', and the "descent line",
  42. which  is the lowest line in characters like 'q' and  'g'.   Other
  43. locations  of  interest are the "half line",  which is the top  of
  44. characters  like  'a' or 'n',  and the "base line",  which is  the
  45. bottom of characters which do not have descenders.
  46.  
  47.      Before  plunging into the Attribute Functions for  text,  you
  48. should  note  that  the  writing  mode  (vswr_mode)  and  clipping
  49. rectangle  (vs_clip) attributes discussed in the last column  (#9)
  50. also  pertain  to  text.   Since much of the  discussion  of  text
  51. optimization  will  center on these attributes,  you may  want  to
  52. review them.
  53.  
  54.      TEXT ATTRIBUTES.   The writing color for graphics text is set
  55. with the command:
  56.  
  57.           vst_color(vdi_handle, color);
  58.  
  59. Vdi_handle  is  always the handle returned from  graf_handle()  at
  60. application startup.  Color is a word value between 0 and 15 which
  61. designates  the  output  color index.   As discussed  in  previous
  62. columns,  the  actual  color  which appears is  dependent  on  the
  63. current  palette  settings.   In  applications such  as  word  and
  64. outline  processors  it  is important that  characters  and  their
  65. background  provide  good contrast to avoid eyestrain.   In  these
  66. situations,  you  may  want to use the setPalette and/or  setColor
  67. XBIOS  functions  to  force the palette to a  known  state  before
  68. starting the application.
  69.  
  70.      You  can choose a variety of special output effects for  your
  71. text with the call:
  72.  
  73.           vst_effects(vdi_handle, effects);
  74.  
  75. Effects is a single flag word,  with the bits having the following
  76. significance:
  77.  
  78.           0 - Thicken
  79.           1 - Lighten
  80.           2 - Skew
  81.           3 - Underline
  82.           4 - Outline
  83.           5 - Shadow
  84.  
  85. In each case,  turning the bit on selects the effect.   Otherwise,
  86. the  effect  is  off.   Any  number of  multiple  effects  may  be
  87. selected, but the result may not always be pleasing or legible.
  88.  
  89.      The  "thicken"  effect widens the character  strokes  by  one
  90. pixel,   resulting  in  the  appearance  of  boldface  type.   The
  91. "lighten" effect superimposes a half-tone dither on the character.
  92. This mode is useful for indicating non-selectable text items,  but
  93. is not legible enough for other purposes.
  94.  
  95.      The  skew effect shifts the rows of the character the  right,
  96. with  the greatest displacement at the top.   This results in  the
  97. appearance of italic text.   You should be aware that the VDI does
  98. not  compensate for this effect.   This means that a skewed italic
  99. character which is immediately followed by a normal blank will  be
  100. overstruck,  and  part of the top of the character will disappear.
  101. Likewise,  a  skewed character written to the left of an  existing
  102. normal  character will overstrike part of it.   There is a related
  103. bug  in  the VDI clipping logic which may cause some  parts  of  a
  104. skewed  character not to be redrawn if they fall at the edge of  a
  105. clipping  rectangle,  even  though  they should  fall  within  the
  106. region.
  107.  
  108.      The  outline  effect  produces output which is  a  one  pixel
  109. "halo" around the normal character.  The shadow effect attempts to
  110. create  a  "drop  shadow" to the side  of  the  character.   These
  111. effects  should be used very sparingly with default  sized  fonts.
  112. They often result in illegible output.
  113.  
  114.      When  graphics text is written,  a screen coordinate must  be
  115. specified  for  the output.   The relationship of the text to  the
  116. screen point is determined by the call:
  117.  
  118.           vst_alignment(vdi_handle, hin, vin, &hout, &vout);
  119.  
  120. Hin  and  vin are each words,  with values specifying the  desired
  121. horizontal  and vertical alignment,  respectively.   Hout and vout
  122. receive the actual values set by the VDI.  If they differ from the
  123. requested values, an error has occurred.
  124.  
  125.      Hin may be set to zero for left justification, one for center
  126. justification,  or  two  for right justification.   The coordinate
  127. given when text is written becomes the "anchor point" as described
  128. in the definitions above.  The default justification is left.
  129.  
  130.      Vin determines what reference line of the text is  positioned
  131. at the output coordinate.  The selection values are:
  132.  
  133.           0 - baseline (default)
  134.           1 - half line
  135.           2 - ascent line
  136.           3 - bottom line
  137.           4 - descent line
  138.           5 - top line
  139.  
  140.      A  common combination of alignments is left (0) and top  line
  141. (5).   This  mode guarantees that all text output will lie to  the
  142. right and below the output coordinate.   This corresponds with the
  143. AES object and GRECT coordinate systems.
  144.  
  145.      Finally, the call to do the actual output is:
  146.  
  147.           v_gtext(vdi_handle, x, y, string);
  148.  
  149. X  and y define the screen coordinate to be used as the  alignment
  150. point.   String  is  a pointer to a null terminated string,  which
  151. must  be total eighty characters or less,  exclusive of the  null.
  152. This limit is imposed by the size of the intin[] array in the  VDI
  153. binding.   Be  warned  that  it  is NOT checked  in  the  standard
  154. binding!  Exceeding it may cause memory to be overwritten.
  155.  
  156.      One Inquire Function is useful with text output.  The call
  157.  
  158.           vqt_attributes(vdi_handle, attrib);
  159.  
  160. reads  back the current attribute settings into the 10 word  array
  161. attrib[].   The  main  items  of interest  are  attrib[6]  through
  162. attrib[9],  which contain the width and height of characters,  and
  163. the  width and height of the character cell in the  current  font.
  164. You  should  rely  on this function to  obtain  size  information,
  165. rather  than using the output of the graf_handle()  function.   On
  166. the ST, graf_handle() always returns sizes for the monochrome mode
  167. system font, which will be incorrect in the color screen modes.
  168.  
  169.      Attrib[1] will contain the current graphics text color as set
  170. by  vst_color().   Attrib[3]  and [4] contain the  horizontal  and
  171. vertical alignment settings, respectively.  Attrib[5] contains the
  172. current writing mode, as set by vswr_mode().
  173.  
  174.      OPTIMIZATION.  The most common complai